Restore the documented BandedMatrices reexports - #82

What broke

f3ec92e ("compat: declare SciMLTesting 2.10 and remove blanket reexports", #81) deleted @reexport using BandedMatrices from src/FastAlmostBandedMatrices.jl, replacing the bare using BandedMatrices with import BandedMatrices + using BandedMatrices: bandwidth, bandwidths.

That silently stripped the package's public surface. using FastAlmostBandedMatrices no longer put BandedMatrix or brand in scope, so the package's own documented construction path stopped working on its own. CI never noticed because the same commit patched every call site: it rewrote every docstring example from brand(Float64, 8, 8, 3, 2) to BandedMatrices.brand(...), added using BandedMatrices to the README, docs/src/index.md and nearly every testset, and added BandedMatrices to test/Project.toml.

That rewrite is the evidence. The documented constructor is AlmostBandedMatrix(bands::BandedMatrix, fill) and every documented example builds bands with brand, so those names are normal documented use of this package.

This is release-blocking: the package is being held out of the release specifically because of this stripped surface.

What this PR does

Per "reexport what is normal documented use, but not whole dependencies", it does not restore the blanket @reexport. It adds an explicit export list, matching the Sundials.jl #553 pattern:

Deliberately not restored, because they are BandedMatrices' own reexports or unrelated to this package: the FillArrays names Fill, Ones, Zeros, Eye; the BandedMatrices module binding itself; symrcm. (The pre-strip surface was all of names(BandedMatrices) — 18 names plus everything FillArrays contributes; this is 12.)

Evidence used to pick the list

1. Docstrings / README / docs: AlmostBandedMatrix(bands::BandedMatrix, fill) is the documented constructor; every example in src/, README.md and docs/src/index.md builds bands with brand. brandn is its direct sibling for the same argument.
2. test/ imports added by the stripping commit — direct evidence the names used to come from the reexport:
   • test/core_tests.jl uses BandedMatrix, brand, band(0), and @test_throws BandError on this package's type;
   • test/qa/alloc_tests.jl uses brand and got a using BandedMatrices added — even though BandedMatrices is not a dependency of test/qa/Project.toml. That import is dropped again here, which incidentally removes a latent failure in the QA lane.
3. bandwidth/bandwidths are the two names the stripping commit itself kept importing, and are how a user queries bandpart(A).

Also in this PR

• Docstring, README and docs examples restored to the unqualified brand(...) / BandedMatrix form; the BandedMatrices. qualifications inside the implementation are dropped too, so the bare import BandedMatrices is gone (the non-public _banded_qr!/banded_qr_lmul! import is untouched).
• README.md and docs/src/api.md now document the reexported surface explicitly, including what is not reexported.
• test/qa/qa.jl: REEXPORTED_API restored and passed as reexports_allow, kept in sync with the export block. Band and BandError carry no docstring upstream in BandedMatrices, so they are listed in api_docs_kwargs = (; ignore = ...); everything else passes the public-API docstring check on its upstream docstring.
• New Core testset "Reexported BandedMatrices API" pins the contract: every approved name is in names(FastAlmostBandedMatrices), in scope from a bare using FastAlmostBandedMatrices, and === the upstream binding; and Fill/Ones/Zeros/Eye/symrcm/BandedMatrices are not exported. The allow-list cannot drift from the exports without a test failure.

Semver

Restoring names that used to be exported is not breaking — it only adds bindings back. No version bump here; a separate release pass handles versions.

Verification actually run (Julia 1.11.8, macOS aarch64)

• Pkg.test() (Core group): 76 pass, 2 broken, 0 fail
• GROUP=QA Pkg.test(): alloc_tests.jl 11 pass, qa.jl 18 pass, 2 broken, 0 fail (the 2 broken are the pre-existing aqua_broken = (:ambiguities,) and ei_broken = (:no_implicit_imports,))
• Runic --check clean over the whole repo
• Sanity check that using FastAlmostBandedMatrices alone now suffices: AlmostBandedMatrix(brand(...), ...), AlmostBandedMatrix(BandedMatrix(...), ...), A[band(0)] .+= 1:n, bandwidths(bandpart(A))

Docs were not built locally.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Rmh6B9eoW3N8oCbuuVPVxJ